Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EOQualifiableDataSources

Adopted By:	EODatabaseDataSource
EODetailDatabaseDataSource

Incorporates:	EODataSources

Declared In:	eoaccess/EODataSources.h

Protocol Description

The EOQualifiableDataSources protocol defines the interface for a data source (as defined in the EODataSources protocol specification) that supplies objects based on a relationship from a source (or ªmasterº) object. For example, suppose a Department object has a relationship giving all Employee objects associated with it. When you qualify a data source on this relationship, that data source supplies all the Employee objects for that department (and no other objects).

The Enterprise Objects Framework provides two classes that adopt this protocol, each with its own behavior. EODetailDatabaseDataSource always works as a detail data source, getting its objects from its master data source and doing no fetching of its own. An EODatabaseDataSource acts as an independent data source, even when set up as the detail of another EODatabaseDataSource. This difference in behavior is explored in the following two sections.

EODetailDatabaseDataSource

An EODetailDatabaseDataSource is a qualifiable data source that accesses objects existing in memory rather than in the external store. It acts as a ªslaveº to its master data source (an EODatabaseDataSource), which retains most of the control in supplying and modifying enterprise objects. The master data source holds the connection to the external source of objects: It fetches all objects for itself and its detail data source, and processes all insertions, updates, and deletions of enterprise objects.

The EODetailDatabaseDataSource gets its objects by traversing relationships of its master's objects, using the relationship key specified in qualifyWithRelationshipKey:ofObject: to get the destination objects for the master object. It performs updates by forwarding operations to its master; a consequence of this is that changes made by a detail data source are immediately visible in the master when the detail data source performs saveObjects.

Because an EODetailDatabaseDataSource accesses objects already fetched into memory, it can't specify a sort order for the objects it supplies. It also doesn't qualify the objects it supplies any further than its relationship specifies; you can't ask an EODetailDatabaseDataSource for all the employees of the Production department who earn more than $40,000, for example.

You usually create an EODetailDatabaseDataSource by sending dataSourceQualifiedByKey: to an EODatabaseDataSource. This method is declared by the EOMasterDataSources protocol. Once you have a detail data source, you use the qualifyWithRelationshipKey:ofObject: method of the EOQualifiableDataSources protocol to choose the source object in the master data source. The detail data source then supplies objects fitting the relationship for the source object.

EODatabaseDataSource as a Qualifiable Data Source

An EODatabaseDataSource can fetch objects on its own, and can restrict the objects it provides with a qualifier narrowing properties of the objects to certain ranges or values. Setting an EODatabaseDataSource up as a detail of another is thus simply another way of setting the qualifier of the data source: only objects matching the relationship for the source object are fetched. The relationship key for such a detail data source, then, is used in a qualifier to fetch the object from the database, as opposed to the key for an EODetailDatabaseDataSource, which is used in a key-value coding message to get the in-memory object for the relationship.

An EODatabaseDataSource qualified in this manner is called a qualified peer data source; it's attached to its master data source, but it works on its own with the external store of objects, fetching and modifying objects directly. Because a qualified peer works independently, the changes it makes may not be immediately visible in its ªmaster.º

Because it fetches objects from the database rather than accessing those already in memory, a qualified peer data source can specify a sort order when retrieving objects, and can qualify those objects beyond its relationship (though it may not in fact provide either feature). For example, you can ask an EODatabaseDataSource to fetch only employees of the Production department who earn more than $40,000 with the setAuxiliaryQualifier: method.

You typically create a qualified peer EODatabaseDataSource by allocating and initializing it yourself. You then send it a qualifyWithRelationshipKey:ofObject: message, with the object being one supplied by the master data source. The master and qualified peer data sources maintain no formal connection with regard to the external store, and operate independently of each other.

Instance Methods

qualifyWithRelationshipKey:ofObject:

- (void)qualifyWithRelationshipKey:(NSString *)relName ofObject:anEO

Qualifies the receiver so that it supplies objects based on relName, which is the name of a relationship of anEO (that is, a key of the form used with the EOKeyValueCoding protocol). If the receiver was created with the dataSourceQualifiedByKey: method of the EOMasterDataSources protocol, relName should be the same name used to create it. If anEO is nil, the detail data source typically supplies nothing; for example, this is useful for temporarily ªturning offº a data source when no records are selected in its master.

Suppose, for example, that an application has a Department entity with a toEmployees relationship. This code excerpt, then, creates a detail data source for employees in the Production department:

id <EOMasterDataSources> deptDataSource;  /* Assume this exists. */
Department *productionDept;               /* Assume this exists. */
id <EOQualifiableDataSources> empSource;

empSource = [deptDataSource dataSourceQualifiedByKey:@"toEmployees"];
[empSource retain];
[empSource qualifyWithRelationshipKey:@"toEmployees"
     ofObject:productionDept];
[empSource fetchObjects];

Once a qualifiable data source has been created, it can be set to retrieve the employees of another department by sending qualifyWithRelationshipKey:ofObject: again. This code excerpt changes empSource to retrieve employees in the System Software department:

Department *sysSoftwareDept;          /* Assume this exists. */

[empSource qualifyWithRelationshipKey:@"toEmployees"
    ofObject:sysSoftwareDept];
[empSource fetchObjects];